Add support for `stop(cause:)`. #388

ioquatix · 2025-05-16T02:51:16Z

Add cause: to Async::Task#stop(cause:) so that extra information about the reason for stopping can be provided. It must be an exception suitable for raise Async::Stop, cause: cause.

Fixes #387.

Types of Changes

New feature.

Contribution

I added tests for my changes.
I tested my changes locally.
I agree to the Developer's Certificate of Origin 1.1.

ioquatix · 2025-05-16T06:14:12Z

I found an issue, Fiber#raise does not seem to support cause: keyword argument correctly. I need to investigate.

macournoyer · 2025-05-16T19:53:36Z

I test w/ a sleep, and sending SIGINT to the worker sleeping. Here's what I got:

Async::Stop: {cause: #<Async::Stop: {cause: #<Async::Stop: {cause: #<Async::Stop: {cause: #<Interrupt: Interrupt>}>}>}>}
/Users/ma/.gem/ruby/3.4.4/bundler/gems/async-53670d16cb43/lib/async/scheduler.rb:221:in 'IO::Event::Selector::KQueue#transfer'
	/Users/ma/.gem/ruby/3.4.4/bundler/gems/async-53670d16cb43/lib/async/scheduler.rb:221:in 'Async::Scheduler#block'
	/Users/ma/.gem/ruby/3.4.4/bundler/gems/async-53670d16cb43/lib/async/scheduler.rb:254:in 'Async::Scheduler#kernel_sleep'

Seems there is too much nesting.

ioquatix · 2025-05-22T09:50:50Z

Two issues:

samuel-williams-shopify · 2025-07-22T22:53:17Z

@macournoyer I was able to understand the cause of the output you are seeing.

fiber = Fiber.new do
  while true
    begin
      Fiber.yield
    rescue Exception => error
      puts "error: #{error.inspect}", "error.cause: #{error.cause.inspect}"
    end
  end
end

fiber.resume

# Example of raising an exception with a cause:
fiber.raise StandardError.new("boom"), cause: StandardError.new("cause")

On 3.4, the cause is not correctly attributed to the error and instead ends up being a keyword argument.

> chruby 3.4
> ruby ./test.rb
error: #<StandardError: {cause: #<StandardError: cause>}>
error.cause: nil

On ruby-head, the cause is correctly attributed to the error (including this PR):

> chruby ruby-head
> ruby ./test.rb
error: #<StandardError: boom>
error.cause: #<StandardError: cause>

Deeply nested cause Async::Stop: {cause: #<Async::Stop: {cause: #<Async::Stop: {cause: #<Async::Stop: {cause: #<Interrupt: Interrupt>}>}>}>} is an artefact of several tasks stopping in sequence. The causality chain is not clearly printed but in 3.5+ it should be.

ioquatix · 2025-07-23T06:13:39Z

Another before/after example:

require_relative "lib/async"

Async do
  sleep
ensure
  Console.error(self, "Task exiting", $!)
end

3.4.4 on main (without this PR)

> chruby 3.4.4
> ruby ./test.rb
^C  0.0s    error: Object [oid=0x20] [ec=0x28] [pid=199670] [2025-07-23 18:23:35 +1200]
               | Task exiting
               | Async::Stop
               |   Async::Stop: Async::Stop
               |   → lib/async/scheduler.rb:191 in 'IO::Event::Selector::URing#transfer'
               |     lib/async/scheduler.rb:191 in 'Async::Scheduler#transfer'
               |     lib/async/scheduler.rb:281 in 'Async::Scheduler#kernel_sleep'
               |     ./test.rb:4 in 'Kernel#sleep'
               |     ./test.rb:4 in 'block in <main>'
               |     lib/async/task.rb:205 in 'block in Async::Task#run'
               |     lib/async/task.rb:443 in 'block in Async::Task#schedule'
/home/samuel/Developer/socketry/async/lib/async/scheduler.rb:453:in 'IO::Event::Selector::URing#select': Interrupt
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:453:in 'Async::Scheduler#run_once!'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:492:in 'Async::Scheduler#run_once'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:568:in 'block in Async::Scheduler#run'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:528:in 'block in Async::Scheduler#run_loop'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:525:in 'Thread.handle_interrupt'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:525:in 'Async::Scheduler#run_loop'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:567:in 'Async::Scheduler#run'
	from /home/samuel/Developer/socketry/async/lib/kernel/async.rb:34:in 'Kernel#Async'

The error encountered from within the task (Async::Stop) has no cause attached.

3.4.4 + this PR

> chruby 3.4.4
> ruby ./test.rb
^C  0.0s    error: Object [oid=0x20] [ec=0x28] [pid=192112] [2025-07-23 18:12:29 +1200]
               | Task exiting
               | {cause: Interrupt}
               |   Async::Stop: {cause: Interrupt}
               |   → lib/async/scheduler.rb:191 in 'IO::Event::Selector::URing#transfer'
               |     lib/async/scheduler.rb:191 in 'Async::Scheduler#transfer'
               |     lib/async/scheduler.rb:281 in 'Async::Scheduler#kernel_sleep'
               |     ./test.rb:4 in 'Kernel#sleep'
               |     ./test.rb:4 in 'block in <main>'
               |     lib/async/task.rb:237 in 'block in Async::Task#run'
               |     lib/async/task.rb:481 in 'block in Async::Task#schedule'
/home/samuel/Developer/socketry/async/lib/async/scheduler.rb:453:in 'IO::Event::Selector::URing#select': Interrupt
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:453:in 'Async::Scheduler#run_once!'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:492:in 'Async::Scheduler#run_once'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:568:in 'block in Async::Scheduler#run'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:528:in 'block in Async::Scheduler#run_loop'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:525:in 'Thread.handle_interrupt'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:525:in 'Async::Scheduler#run_loop'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:567:in 'Async::Scheduler#run'
	from /home/samuel/Developer/socketry/async/lib/kernel/async.rb:34:in 'Kernel#Async'
	from ./test.rb:3:in '<main>'

The error encountered from within the task has an odd keyword argument attached.

HEAD + this PR

> chruby ruby-head
> ruby ./test.rb
^C  0.0s    error: Object [oid=0x20] [ec=0x28] [pid=192193] [2025-07-23 18:12:34 +1200]
               | Task exiting
               | Task was stopped
               |   Async::Stop: Task was stopped
               |   → lib/async/scheduler.rb:191 in 'IO::Event::Selector::URing#transfer'
               |     lib/async/scheduler.rb:191 in 'Async::Scheduler#transfer'
               |     lib/async/scheduler.rb:281 in 'Async::Scheduler#kernel_sleep'
               |     ./test.rb:4 in 'Kernel#sleep'
               |     ./test.rb:4 in 'block in <main>'
               |     lib/async/task.rb:237 in 'block in Async::Task#run'
               |     lib/async/task.rb:481 in 'block in Async::Task#schedule'
               |   Caused by Interrupt: Interrupt
               |   → /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:453 in 'IO::Event::Selector::URing#select'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:453 in 'Async::Scheduler#run_once!'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:492 in 'Async::Scheduler#run_once'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:568 in 'block in Async::Scheduler#run'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:528 in 'block in Async::Scheduler#run_loop'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:525 in 'Thread.handle_interrupt'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:525 in 'Async::Scheduler#run_loop'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:567 in 'Async::Scheduler#run'
               |     /home/samuel/Developer/socketry/async/lib/kernel/async.rb:34 in 'Kernel#Async'
               |     ./test.rb:3 in '<main>'
/home/samuel/Developer/socketry/async/lib/async/scheduler.rb:453:in 'IO::Event::Selector::URing#select': Interrupt
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:453:in 'Async::Scheduler#run_once!'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:492:in 'Async::Scheduler#run_once'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:568:in 'block in Async::Scheduler#run'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:528:in 'block in Async::Scheduler#run_loop'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:525:in 'Thread.handle_interrupt'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:525:in 'Async::Scheduler#run_loop'
	from /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:567:in 'Async::Scheduler#run'
	from /home/samuel/Developer/socketry/async/lib/kernel/async.rb:34:in 'Kernel#Async'
	from ./test.rb:3:in '<main>'

The cause is correctly attached.

HEAD (without this PR)

Interestingly enough, Fiber#raise automatically uses the current exception ($!) as cause, the same as Kernel#raise. Therefore, while this PR has some ergonomic advantages, it's not strictly needed:

> chruby ruby-head
> git checkout main
> ruby ./test.rb
^C  0.0s    error: Object [oid=0x20] [ec=0x28] [pid=201905] [2025-07-23 18:26:59 +1200]
               | Task exiting
               | Async::Stop
               |   Async::Stop: Async::Stop
               |   → lib/async/scheduler.rb:191 in 'IO::Event::Selector::URing#transfer'
               |     lib/async/scheduler.rb:191 in 'Async::Scheduler#transfer'
               |     lib/async/scheduler.rb:281 in 'Async::Scheduler#kernel_sleep'
               |     ./test.rb:4 in 'Kernel#sleep'
               |     ./test.rb:4 in 'block in <main>'
               |     lib/async/task.rb:205 in 'block in Async::Task#run'
               |     lib/async/task.rb:443 in 'block in Async::Task#schedule'
               |   Caused by Interrupt: Interrupt
               |   → /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:453 in 'IO::Event::Selector::URing#select'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:453 in 'Async::Scheduler#run_once!'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:492 in 'Async::Scheduler#run_once'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:568 in 'block in Async::Scheduler#run'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:528 in 'block in Async::Scheduler#run_loop'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:525 in 'Thread.handle_interrupt'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:525 in 'Async::Scheduler#run_loop'
               |     /home/samuel/Developer/socketry/async/lib/async/scheduler.rb:567 in 'Async::Scheduler#run'
               |     /home/samuel/Developer/socketry/async/lib/kernel/async.rb:34 in 'Kernel#Async'
               |     ./test.rb:3 in '<main>'

Cause is correctly attached in this case (but there are some cases where it won't be).

ioquatix · 2025-07-24T03:08:24Z

Okay, the changes to CRuby were merged. We just need to make this work as best we can across different Ruby versions.

… for older Ruby versions.

ioquatix force-pushed the async-stop-cause branch 3 times, most recently from 1aee925 to 53670d1 Compare May 16, 2025 05:25

ioquatix force-pushed the main branch from 0a89d60 to e9732d1 Compare July 11, 2025 22:36

samuel-williams-shopify force-pushed the async-stop-cause branch from 53670d1 to dcf42b9 Compare July 22, 2025 12:22

ioquatix mentioned this pull request Jul 22, 2025

Support cause: in Thread#raise and Fiber#raise. ruby/ruby#13967

Merged

ioquatix force-pushed the async-stop-cause branch from dcf42b9 to e208922 Compare July 23, 2025 06:36

ioquatix and others added 2 commits July 24, 2025 16:09

Add support for stop(cause:).

a1d1004

Add test for 3.5+.

3789e09

ioquatix force-pushed the async-stop-cause branch 2 times, most recently from 0f89936 to 195cf8c Compare July 24, 2025 06:45

Move Async::Stop to lib/async/stop.rb and implement compatibility…

33811a5

… for older Ruby versions.

ioquatix force-pushed the async-stop-cause branch from 195cf8c to 33811a5 Compare July 24, 2025 07:47

ioquatix mentioned this pull request Jul 24, 2025

Forward **options in raise. socketry/io-event#147

Merged

3 tasks

ioquatix enabled auto-merge (squash) July 24, 2025 08:30

ioquatix disabled auto-merge July 24, 2025 08:31

ioquatix merged commit e9703fd into main Jul 24, 2025
82 of 111 checks passed

ioquatix deleted the async-stop-cause branch July 24, 2025 08:31

ioquatix mentioned this pull request Jul 26, 2025

Graceful shutdown socketry/falcon#71

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add support for `stop(cause:)`. #388

Add support for `stop(cause:)`. #388

Uh oh!

ioquatix commented May 16, 2025 •

edited by samuel-williams-shopify

Loading

Uh oh!

ioquatix commented May 16, 2025

Uh oh!

macournoyer commented May 16, 2025

Uh oh!

ioquatix commented May 22, 2025

Uh oh!

samuel-williams-shopify commented Jul 22, 2025 •

edited

Loading

Uh oh!

ioquatix commented Jul 23, 2025 •

edited

Loading

Uh oh!

ioquatix commented Jul 24, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Add support for stop(cause:). #388

Add support for stop(cause:). #388

Uh oh!

Conversation

ioquatix commented May 16, 2025 • edited by samuel-williams-shopify Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Types of Changes

Contribution

Uh oh!

ioquatix commented May 16, 2025

Uh oh!

macournoyer commented May 16, 2025

Uh oh!

ioquatix commented May 22, 2025

Uh oh!

samuel-williams-shopify commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ioquatix commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

3.4.4 on main (without this PR)

3.4.4 + this PR

HEAD + this PR

HEAD (without this PR)

Uh oh!

ioquatix commented Jul 24, 2025

Uh oh!

Uh oh!

Uh oh!

Add support for `stop(cause:)`. #388

Add support for `stop(cause:)`. #388

ioquatix commented May 16, 2025 •

edited by samuel-williams-shopify

Loading

samuel-williams-shopify commented Jul 22, 2025 •

edited

Loading

ioquatix commented Jul 23, 2025 •

edited

Loading